home *** CD-ROM | disk | FTP | other *** search
/ Complete Linux / Complete Linux.iso / docs / apps / database / postgres / postgre2.z / postgre2 / doc / implementation / catalogs.me < prev    next >
Encoding:
Text File  |  1992-08-27  |  14.4 KB  |  453 lines
  1. .\"----------------------------------------------------------------------
  2. .\" FILE
  3. .\"    catalogs.tt
  4. .\"
  5. .\" DESCRIPTION
  6. .\"    Spec for the system catalogs.
  7. .\"
  8. .\" RCS ID
  9. .\"    $Header: /private/postgres/doc/implementation/RCS/catalogs.me,v 1.1 1990/07/30 13:50:14 kemnitz Exp $
  10. .\"----------------------------------------------------------------------
  11. .nr tp 12
  12. .nr fp 11
  13. .nr sp 12
  14. .nr pp 12
  15. .sz 12
  16. .fo ''%''
  17. .(l C
  18. .sz 14
  19. .b
  20. POSTGRES System Catalogs
  21. .sz 11
  22. .nr pp 11
  23. .sp
  24. (Version of: $Date: 1990/07/30 13:50:14 $)
  25. .r
  26. .sp
  27. (Printed: \*(td)
  28. .)l
  29. .sh 1 "Introduction"
  30. .pp
  31. This note describes the current proposal for the POSTGRES
  32. system catalogs.
  33. Table 1 lists the names of all the catalogs, whether each is
  34. local to a database (i.e., local) or shared with all databases
  35. (i.e., global), and what the catalog contains.
  36. .(z
  37. .hl
  38. .TS
  39. center;
  40. l | l | l.
  41. \fBName    Scope    Entry for each...\fP
  42. _
  43. AGGREGATE    local    aggregate function.
  44. AM    local    access method.
  45. AMOP    local    (access method, op class, op).
  46. ATTRIBUTE    local    relation attribute.
  47. DATABASE    global    database of current databases.
  48. DEFAULTS    global    default values.
  49. DEMON    global    system demon.
  50. INDEX    local    secondary index.
  51. INHERITPROC    local    inherited procedure.
  52. INHERITS    local    direct relation/parent relationship.
  53. IPL    local    inheritance precedence list entry.
  54. LANGUAGE    local    language in which a procedure can be written.
  55. MAGIC    global    magic constant in source code.
  56.     ???    shouldn't this be local??? --hirohama
  57. OPCLASS    local    adt?? operator class.
  58. OPERATOR    local    adt?? operator.
  59. PARG    local    argument to a procedure.
  60. PROC    local    procedure.
  61. RELATION    local    relation.
  62. RULE    local    rule.
  63. RULEPLANS    local    plans needed by the rule manager.
  64. SERVER    global    active POSTGRES backend..
  65. STATISTIC    local    relation attribute.
  66. TYPE    local    data type.
  67. USER    global    valid user.
  68. VARIABLE    global    special variable values.
  69. VERSION    local    version.
  70. .TE
  71. .sp
  72. .ce
  73. Table 1: Catalog summary.
  74. .hl
  75. .)z
  76. .pp
  77. References to the system catalog relations
  78. should always be in lower case and be prepended
  79. with \*(lqpg_\*(rq.
  80. For example, the RELATION relation should be
  81. referenced as \*(lqpg_relation\*(rq.
  82. .pp
  83. The primitive data types used in the catalog definitions 
  84. are listed in Table 2.
  85. .(z
  86. .hl
  87. .TS
  88. center;
  89. l | l.
  90. \fBData Type    Description\fP
  91. _
  92. bool    boolean (stored as byte).
  93. byte    uninterpreted byte
  94. int2    2 byte integer.
  95. u_int2    unsigned 2 byte integer.
  96. int4    4 byte integer.
  97. u_int4    unsigned 4 byte integer.
  98. float4    4 byte floating point.
  99. float8    8 byte floating point.
  100. char    character.
  101. text    variable length text.
  102. abstime    absolute date and time.
  103. reltime    relative date and time.
  104. regproc    register procedure.
  105. postquel    POSTQUEL commands.
  106. .TE
  107. .sp
  108. .ce
  109. Table 2. Predefined data types.
  110. .hl
  111. .)z
  112. In addition to the types listed,
  113. fixed length arrays of primitive types are supported
  114. by the system.
  115. For example, an array of integers with five elements
  116. is specified by \*(lqint[5].\*(rq
  117. Attributes of type POSTQUEL procedure can also be defined.
  118. An attribute that contains a different procedure in every tuple
  119. is declared to be of type ``postquel''.
  120. An attribute that contains a parameterized procedure in every tuple
  121. (i.e., the procedure is the same for all entries) is declared to
  122. be of a user-defined type, where the type defines a parameterized
  123. query.
  124. In the descriptions below, type names of the form ``t_\fIx\fP'' are 
  125. type procedures.
  126. .(b F
  127. .i
  128. Attributes of type REGPROC procedure are currently being used
  129. in lieu of a form of compact POSTQUEL,
  130. since POSTQUEL procedures are not yet implemented.
  131. The value of a REGPROC attribute
  132. is the \fPproname\fI of a registered procedure,
  133. represented interally by the OID of the PROC relation tuple
  134. associated with this procedure.
  135. .\" The system is designed to allow new languages to be easily added.
  136. .\" Arguments to a registered procedure are
  137. .\" typed checked when the procedure is called. ???
  138. .\" Registered procedures may be written in C, LISP, or POSTQUEL.
  139. .\" A postquel value contains the following fields:
  140. .\"    iscached    /* is the proc precomputed? */
  141. .\"    src    /* source code */
  142. .\"    bin    /* binary code */
  143. .\"    result    /* precomputed result */
  144.  
  145. .r
  146. .)b
  147. A naming convention is followed for all relation attributes.
  148. The name of each attribute in a relation begins with the first
  149. three characters of the relation name.
  150. For example, the attribute \fIrelname\fP in the RELATION relation
  151. contains the name of the relation, version, or index being defined.
  152. .pp
  153. Eight kinds of entities are defined in the catalogs: users, relations, 
  154. data types, operators, access methods, rules, demons, and procedures.
  155. Each instance of an entity has a unique identifier.
  156. Foreign keys are represented by the unique identifier of the
  157. instance in the appropriate relation.
  158. The type of the foreign key is specified as the entity name
  159. for documentation purposes.
  160. The actual value stored will be a \*(lqoid\*(rq.
  161. Oid's values will be unique across all relations (including history
  162. and versions) in the database.
  163. .pp
  164. The remainder of this note defines the catalogs for representing
  165. these entities.
  166. .de bs    \" define macro to begin each section...
  167. .sp
  168. .in -4n
  169. .fi
  170. .sh 1 "\\$1"
  171. .ta 0.4i +2.25i
  172. .lp
  173. .nf
  174. .in +4n
  175. ..
  176. .in +4n
  177. .bs "Users"
  178. USER(
  179.     usename = char[16],    /* user's name */
  180.     usesysid = int2,    /* user system id (UNIX uid) */
  181.     usecreatedb = bool,    /* can user create databases? */
  182.     usetrace = bool,    /* can user set trace flags? */
  183.     usesuper = bool,    /* can user be super user? */
  184.     usecatupd = bool    /* can user update catalogs? */
  185. )
  186. DATABASE(
  187.     datname = char[16],    /* database name */
  188.     datdba = USER,    /* database administrator */
  189.     datpath = text    /* directory of database */
  190. )
  191. DEFAULTS(
  192.     defname = char[16],    /* default name */
  193.     defvalue = byte[16]    /* default value */
  194. )
  195. VARIABLE(
  196.     varname = char[16],    /* variable name */
  197.     varvalue = byte[]    /* variable value */
  198. )
  199. MAGIC(
  200.     magname = char[16],    /* constant name */
  201.     magvalue = byte[16]    /* constant value */
  202. )
  203. .(b F
  204. .i
  205. .lp
  206. One copy of these catalogs will be maintained on each host.
  207. They will be mapped to all user databases.
  208. .)b
  209. .bs "Relations"
  210. RELATION(
  211.     relname = char[16],    /* relation name */
  212.     relowner = USER,    /* relation owner */
  213.     relam = AM,    /* access method */
  214.     relpages = u_int4,    /* # pages */
  215.     reltuples = u_int4,    /* # tuples */
  216.     relexpires = abstime,    /* time after which tuples are deleted */
  217.     relpreserved = reltime,    /* time after which tuples are deleted */
  218.     relhasindex = bool,    /* is relation indexed? */
  219.     relisshared = bool,    /* is relation shared? */
  220.     relkind = char,    /* kind of relation ...
  221.          * oneof(\*(lqindex\*(rq, \*(lqrelation\*(rq, \*(lqspecial\*(rq,
  222.          * \*(lquncataloged\*(rq, \*(lqversion\*(rq) */
  223.     relarch = char,    /* relation archive mode... 
  224.          * oneof(\*(lqheavy\*(rq, \*(lqlight\*(rq, \*(lqnone\*(rq) */
  225.     relnatts = u_int2,    /* current number of attributes */
  226.     relkey = int2[8],    /* attribute number of relation keys */
  227.     relkeyop = OPERATOR[8],    /* oid's of key attr op's */
  228.     reldesc = t_reldesc    /* cached relation descriptor */
  229.     reclusterindex = RELATION     /* index on which relation is clustered */
  230. )
  231.  
  232. ATTRIBUTE(
  233.     attrelid = RELATION,    /* relation containing attribute */
  234.     attname = char[16],    /* attribute name */
  235.     atttypid = TYPE,    /* attribute type */
  236.     attdefrel = RELATION,    /* relation that defines the attribute */
  237.     attnvals = u_int4,    /* # distinct values in column */
  238.     atttyparg = TYPE,    /* type arg for arrays */
  239.     attlen = int2,    /* length of attribute (negative means var.) */
  240.     attnum = u_int2,    /* attribute number (temp. int2--exec. bug) */
  241.     attbound = u_int2,    /* upper bound if array */
  242.     attbyval = bool,    /* passed by value (copied from type rel.) */
  243.     attcanindex = bool,    /* indexable domain */
  244.     attproc = PROC    /* procedure for attribute (spquel) */
  245. )
  246.  
  247. INHERITS(
  248.     inhrel = RELATION,    /* inherting relation */
  249.     inhparent = RELATION,    /* inherits from this parent */
  250.     inhseqnum = int4    /* inherits clause order */
  251. )
  252.  
  253. INDEX(
  254.     indexrelid = RELATION,    /* index relation */
  255.     indrelid = RELATION,    /* relation being indexed */
  256.     indkey = u_int2[8],    /* index key attribute numbers */
  257.     indclass = OPCLASS[8],    /* index key classes */
  258.     indisclustered = bool,    /* is relation clustered on this index? */
  259.     indisarchived = bool,    /* is the index archival? */
  260.     inddesc = t_inddesc    /* cached index descriptor */
  261. )
  262.  
  263. VERSION(
  264.     verrelid = RELATION,    /* version relation */
  265.     verbaseid = RELATION,    /* base relation */
  266.     vertime = abstime    /* time for base relation */
  267. )
  268.  
  269. STATISTIC(
  270.     starelid = RELATION,    /* relation being described */
  271.     staattnum = u_int2,    /* attribute # */
  272.     staop = OPERATOR,    /* operator */
  273.     stalokey = text,    /* low value (updated by demon) */
  274.     stahikey = text    /* hi value (updated by demon) */
  275. )
  276. .bs "Data Types"
  277. TYPE(
  278.     typname = char[16],    /* data type name */
  279.     typowner = USER,    /* data type owner */
  280.     typlen = int2,    /* rep size in bytes */
  281.     typprtlen = int2,    /* print rep size in bytes */
  282.     typbyval = bool,    /* passed by value */
  283.     typisproc = bool,    /* is type a procedure? */
  284.     typprocid = PROC,    /* proc oid if it is a procedure */
  285.     typelem = TYPE,    /* array element type */
  286.     typinput = regproc,    /* blank portal input procedure */
  287.     typoutput = regproc,    /* blank portal output procedure */
  288.     typreceive = regproc,    /* input procedure for remote machine front ends */
  289.     typsend = regproc,    /* output procedure for remote machine front ends*/
  290.     typdefault = text    /* default value */
  291. )
  292.  
  293. OPERATOR(
  294.     oprname = char[16],    /* operator name */
  295.     oprowner = USER,    /* operator owner */
  296.     oprprec = u_int2,    /* precedence (should be u_int1) */
  297.     oprkind = char,    /* kind of operator...
  298.          * oneof(\*(lqbinary\*(rq, \*(lqleftunary\*(rq, \*(lqrightunary\*(rq) */
  299.     oprisleft = bool,    /* is operator left associative? */
  300.     oprcanhash = bool,    /* can hash-join use this operator? */
  301.     oprleft = TYPE,    /* left operand type */
  302.     oprright = TYPE,    /* right operand type */
  303.     oprresult = TYPE,    /* result type */
  304.     oprcom = OPERATOR,    /* commutative operator */
  305.     oprnegate = OPERATOR,    /* negated operator */
  306.     oprlsortop = OPERATOR,    /* left merge-sort operator */
  307.     oprrsortop = OPERATOR,    /* right merge-sort operator */
  308.     oprcode = regproc,    /* code for operator */
  309.     oprrest = regproc,    /* proc to estimate restriction selectivity */
  310.     oprjoin = regproc    /* proc to estimate join selectivity */
  311. )
  312.  
  313. OPCLASS(
  314.     opcname = char[16]    /* operator class name */
  315. )
  316.  
  317. .bs "Access Methods"
  318. AM(
  319.     amname = char[16],    /* access method name */
  320.     amowner = USER,    /* access method owner */
  321.     amkind = char,    /* kind of access method...
  322.          * oneof(\*(lqhashed\*(rq, \*(lqordered\*(rq, \*(lqspecial\*(rq) */
  323.     amgettuple = regproc,    /* gettuple proc (required)  */
  324.     aminsert = regproc,    /* insert proc (required) */
  325.     amdelete = regproc,    /* delete proc (required) */
  326.     amgetattr = regproc,    /* getattr proc (optional) */
  327.     amsetlock = regproc,    /* setlock proc (optional) */
  328.     amsettid = regproc,    /* settid proc (optional) */
  329.     amfreetuple = regproc,    /* freetuple proc (optional) */
  330.     ambeginscan = regproc,    /* beginscan proc (optional) */
  331.     amrescan = regproc,    /* rescan proc (optional) */
  332.     amendscan = regproc,    /* endscan proc (optional) */
  333.     ammarkpos = regproc,    /* markpos proc (optional) */
  334.     amrestrpos = regproc,    /* restrpos proc (optional) */
  335.     amopen = regproc,    /* open proc (optional) */
  336.     amclose = regproc,    /* close proc (optional) */
  337.     ambuild = regproc,    /* constructor proc (optional) */
  338.     amcreate = regproc,    /* create proc (optional) */
  339.     amdestroy = regproc    /* destroy proc (optional) */
  340.     amnumslots = u_int2,    /* number of slots for this access method */
  341.     amsortorder = u_int2,    /* slot number which defines ordering of tuples */
  342.     ambuildoperator = u_int2,    /* use this operator to sort tuples
  343.                  * before building index */
  344. )
  345.  
  346. AMOP(
  347.     amopamid = AM,    /* oid of access method */
  348.     amopclaid = OPCLASS,    /* operator class */
  349.     amopoprid = OPERATOR,    /* access method operator */
  350.     amopstrategy = u_int2,    /* strategy number for access method */
  351.     amopselect = regproc,    /* operator selectivity */
  352.     amopnpages = regproc    /* # pages to be examined */
  353. )
  354. .bs "Rules"
  355. RULE(
  356.     rulname = char[16],    /* rule name */
  357.     rulowner = USER,    /* rule owner */
  358.     rulserver = SERVER,    /* server that invoked rule */
  359.     rulportal = char[16],    /* portal name if alerter */
  360.     rulpriority = u_int2,    /* rule priority */
  361.     rulstatus = char,    /* rule implementation status...
  362.          * oneof(``early'', ``late'', ``either-early'',
  363.          *      ``either-late'') */
  364.     rulkind = char,        /* kind of rule...
  365.          * oneof(``once'', ``never'', ``always'') */
  366.     rulstat1 = regproc,    /* statistic (to be filled in by spiros */
  367.         /* postquel/PROC ??? */
  368.     rulstat2 = regproc    /* statistic (to be filled in by spiros */
  369.         /* postquel/PROC ??? */
  370. )
  371.  
  372. RULEPLANS(
  373.     rplrulid = RULE,    /* the OID of the corresponding rule */
  374.     rplnum = u_int2,    /* each rule may have many plans... */
  375.     rplcode = postquel    /* plan code  <implemented as text for the time being> */
  376. )
  377. .bs "Procedures"
  378. PROC(
  379.     proname = char[16],    /* procedure name */
  380.     proowner = USER,    /* procedure owner */
  381.     prolang = LANGUAGE,    /* proc language */
  382.     proisinh = bool,    /* is procedure inheritable? */
  383.     proistrusted = bool,    /* is proc spawned or called? */
  384.     proiscachable = bool,    /* is value precomputable? */
  385.     pronargs = u_int2,    /* number of args */
  386.     prorettype = TYPE,    /* procedure return type */
  387.     prosrc = text,    /* procedure source */
  388.     probin = byte[],    /* procedure binary */
  389.     prodesc = t_procdesc    /* cached procedure descriptor */
  390. )
  391.  
  392. LANGUAGE(
  393.     lanname = char[16],    /* language name */
  394.     lancompiler = text    /* compiler filename */
  395. )
  396.  
  397. PARG(
  398.     parproid = PROC,    /* procedure oid */
  399.     parnum = u_int2,    /* arg # */
  400.     parbound = u_int1,    /* array bound */
  401.     partype = TYPE    /* arg type */
  402. )
  403.  
  404. AGGREGATE(
  405.     aggname = char[16],    /* aggregate name */
  406.     aggowner = USER,    /* aggregate owner */
  407.     aggfun1 = regproc,    /* transition function */
  408.     aggfun2 = regproc    /* completion function */
  409. )
  410. .\".sp
  411. .\".(b F
  412. .\".i
  413. .\"Aggregates use a stateless procedure to compute the aggregate.
  414. .\"For example, the procedure to compute the \*(lqAVG\*(rq aggregate would
  415. .\"have the following procedure header:
  416. .\".nf
  417. .\".sp 0.5v
  418. .\"\fBprocedure\fP AVG(partial-result, n, next-value) 
  419. .\"       \fBreturns\fP partial-result
  420. .\".)b
  421. .\".sp
  422. .\".ne 5
  423. IPL(
  424.     iplrel = RELATION,    /* relation for which ipl is defined */
  425.     iplinherits = RELATION,    /* inherits from relation */
  426.     iplseqnum = int4    /* ipl sequence number */
  427. )
  428.  
  429. INHERITPROC(
  430.     inhproname = char[16],    /* procedure name */
  431.     inhargrel = RELATION,    /* argument relation */
  432.     inhdefrel = RELATION,    /* defining relation */
  433.     inhproc = PROC    /* proc definition */
  434. )
  435. .bs "Demons"
  436. DEMON(
  437.     demserid = SERVER,    /* server oid */
  438.     demname = char[16],    /* demon name */
  439.     demowner = USER,    /* demon owner */
  440.     demcode = regproc    /* demon code */
  441. )
  442.  
  443. SERVER(
  444.     sername = char[16],    /* unique process name */
  445.     serpid = u_int2,    /* unix process id */
  446.     serport = u_int2    /* unix communication port for this process */
  447. )
  448. .(b F
  449. .i
  450. Every POSTGRES backend (i.e., server) will have an entry in SERVER.
  451. Every demon and the POSTMASTER will have an entry in DEMON.
  452. .)b
  453.